Skip unchanged setWifiOnly writes and put the cause in E_STORAGE - #69

What was wrong

In production, E_STORAGE rejects come from iOS only. In 14 days: setWifiOnly 32 users (Sentry DIANA-3427), updateHeaders 17 users, enqueue "cannot save" 16 users. There are two problems.

1. setWifiOnly() wrote the settings file on every call, also when the value did not change. This was true on both platforms. Diana calls it at every app start. So on a nearly full disk, the call failed at startup for no reason.
2. Several rejects did not include the cause. setWifiOnly, updateHeaders, pause, resume and the cancel journal path on iOS logged the error with NSLog only. So we could not tell the Sentry events apart.

What changes

Unchanged setWifiOnly. A call with the current value writes nothing and resolves. A changed value writes as before.

• iOS: setWifiOnly returns early when settings.wifiOnly already has the value. configure() with the same options also writes nothing now.
• Android: QueueSettingsStore.update skips the write when the transform changes nothing. So on Android, pause, resume and the configure() retry defaults also skip an unchanged write. iOS pause and resume already did this (changeGate).

No partly written tmp file on iOS. When FileIO.writeAtomically fails after it creates the .tmp file (for example ENOSPC during the write), it now deletes the .tmp file. Before, that file stayed and held space that a retry needs. Android already did this.

The cause in every E_STORAGE message. The code stays E_STORAGE. The message text before stays the same. A suffix (cause: …) is added. Diana reads only the code (refusalCode), so no decision in Diana changes. Only the Sentry text changes.

iOS sites and their new message shape:

POSIX <n> comes from the NSUnderlyingErrorKey chain. It is left out when the error is already in NSPOSIXErrorDomain or when there is no POSIX error. The description is left out when the message already has it.

Android sites:

errno <NAME> appears only when the cause chain holds an android.system.ErrnoException. QueueException now has a cause. The catch-all still rejects E_STORAGE.

Android rename and directory create. AtomicFiles used File.renameTo and File.mkdirs, which return only a Boolean. It now uses Files.move(..., ATOMIC_MOVE) and Files.createDirectories. Their exceptions say why, for example Permission denied. I did not use android.system.Os.rename, which would also put an ErrnoException in the chain: Os is a stub in the JVM unit tests ("Method rename in android.system.Os not mocked"), so every test that writes a file would fail.

How iOS gets an errno. FileManager.createFile returns only a Bool. Apple does not document that it sets errno. So FileIO.writeSynced and the multipart writer now create the file with POSIX open(O_WRONLY|O_CREAT|O_TRUNC, 0644). A failure throws an NSPOSIXErrorDomain error. FileIO.rename now throws the same kind of error. Its text still has errno <n>.

I did not add a structured userInfo.cause. A comment in FileIO.cause and StorageCause names it as a later option.

Where to look

• iOS: FileIO.cause, FileIO.create, FileIO.posixError, FileIO.writeAtomically in ios/FileIO.swift. configure, setWifiOnly, changeGate, updateHeaders, cancel and saveSettings in ios/QueueCoordinator.swift.
• iOS: settle in ios/QueueCoordinator+Outcomes.swift has two forms now. settle(id, outcome) never throws. settle(id, outcome, requireJournal: true) throws the journal error, so cancel can put it in the message. EventJournal.appendOrThrow is the throwing form of append.
• Android: StorageCause.kt (new), QueueSettingsStore.update, AtomicFiles.writeAtomically, the QueueException wraps in QueueController.kt, and onQueue in UploaderModule.kt.
• README: one sentence under setWifiOnly, and one next to the codes: E_STORAGE messages are for logs, so match on code.

Risks

• Sentry grouping. Where Diana uses default grouping, a new message text can split or merge issues. JS errors usually group by stack, so I expect no change. Not checked.
• File protection on iOS. A file made with open() gets the app's default data protection class, as createFile with no attributes does.

Test plan

• cd ios && swift test: 245 tests, 0 failures. Before: 235. New in ios/Tests/StorageCauseTests.swift:
  • The same setWifiOnly value writes once. The test deletes settings.json after the first call and checks that the second call does not create it again.
  • A changed value still writes.
  • The same value resolves when the store directory is read-only.
  • Two configure() calls with the same options write once.
  • A write that fails after the .tmp file exists leaves no .tmp file. The test sets a file size limit (RLIMIT_FSIZE, with SIGXFSZ ignored), so write(2) fails with EFBIG part way, as ENOSPC would.
  • setWifiOnly, updateHeaders, pause and resume on a read-only store reject with … cannot save the queue settings (cause: NSPOSIXErrorDomain 13; cannot create settings.json.tmp….
  • The live cancel with a read-only journal rejects with the cause.
  • An enqueue that cannot make its entry directory ends with (cause: NSCocoaErrorDomain 513; POSIX 13).
  • A form enqueue whose multipart file cannot be created rejects with enqueue: cannot create the form body (cause: NSPOSIXErrorDomain 13; ….
  • The formatter with a nested POSIX error.
  • With the fix removed, each of these fails: the 2 unchanged setWifiOnly tests, the configure test and the .tmp test.
• Android :react-native-background-upload:testDebugUnitTest: 337 tests, 0 failures. Before: 327.
  • New tests in QueueControllerTest cover the same setWifiOnly cases, the catch-all message of a failed settings write, and the cause on a failed cancel journal write. With the skip in update removed, the 2 unchanged-value tests fail.
  • New StorageCauseTest covers the formatter, including ; errno EACCES for an ErrnoException in the cause chain. On the JVM the android.jar stub leaves errno at 0 and cannot name it, so the test replaces the StorageCause.errnoNameOf seam. The default reader (ErrnoException.errno plus OsConstants.errnoName) runs only on a device, so no unit test covers it. It shows on an emulator with a read-only queue directory.
  • A new QueueStoreTest checks that a failed rename throws a FileSystemException and leaves no .tmp file.
  • UploaderModule has no unit tests. The test checks StorageCause.rejectMessage, which onQueue calls.
• yarn lint:ci, yarn typecheck, yarn jest (194 pass). This change touches no JS.

🤖 Generated with Claude Code